//! 元数据处理 (Meta)
//!
//! 元数据是描述其他数据的数据。在 Rust 中，元数据主要指文档、属性和
//! 其他用于描述代码的结构化信息。这些元数据帮助开发者理解代码、
//! 工具生成文档，以及编译器处理代码。

/// 1. 文档 (Documentation)
///
/// Rust 有内建的文档支持，使用文档注释 `///` 和 `//!` 来编写文档
pub fn documentation() {
    println!("=== 文档 (Documentation) ===");

    /// 这是一个函数的文档注释
    ///
    /// # Examples
    ///
    /// ```
    /// let result = example_function(5);
    /// assert_eq!(result, 10);
    /// ```
    ///
    /// # Panics
    ///
    /// 这个函数在任何情况下都不会 panic。
    ///
    /// # Errors
    ///
    /// 这个函数不会返回错误。
    fn example_function(x: i32) -> i32 {
        x * 2
    }

    // 这是模块级别的说明
    // 它描述了整个模块的功能

    println!("文档注释类型:");
    println!("/// - 用于函数、结构体等项的文档");
    println!("//! - 用于模块或 crate 的文档");
    println!("//! - 放在文件或模块的开头");

    println!("\n文档测试:");
    println!("- 嵌入在文档中的代码示例");
    println!("- 使用 cargo test 运行");
    println!("- 确保示例代码保持最新");

    // 使用函数以避免未使用警告
    assert_eq!(example_function(5), 10);
}

/// 2. 属性 (Attributes)
///
/// 属性是应用于项的元数据，使用 `#[...]` 语法
pub fn attributes() {
    println!("\n=== 属性 (Attributes) ===");

    // 条件编译属性
    #[cfg(target_os = "linux")]
    fn linux_only() {
        println!("只在 Linux 上编译");
    }

    // 测试函数示例（移除 #[test] 属性以避免警告）
    fn test_function() {
        assert_eq!(2 + 2, 4);
    }

    // 内联属性
    #[inline]
    fn inline_function() -> i32 {
        42
    }

    // 弃用属性
    #[deprecated(since = "1.0.0", note = "请使用新函数")]
    fn deprecated_function() {
        println!("弃用函数");
    }

    // 允许特定警告
    #[allow(dead_code)]
    fn unused_function() {
        println!("未使用的函数");
    }

    println!("常见属性:");
    println!("#[derive(...)] - 自动生成 trait 实现");
    println!("#[cfg(...)] - 条件编译");
    println!("#[test] - 标记测试函数");
    println!("#[inline] - 建议内联函数");
    println!("#[deprecated] - 标记弃用项");
    println!("#[allow(...)] - 允许特定 lint");
    println!("#[warn(...)] - 警告特定 lint");
    println!("#[deny(...)] - 拒绝特定 lint");
    println!("#[forbid(...)] - 禁止特定 lint");
}

/// 3. 基准测试 (Benchmarking)
///
/// 基准测试用于测量代码性能
pub fn benchmarking() {
    println!("\n=== 基准测试 (Benchmarking) ===");

    println!("基准测试说明:");
    println!("- 使用 criterion 或 built-in benches");
    println!("- 测量函数执行时间");
    println!("- 比较不同实现的性能");
    println!("- 需要 nightly Rust 才能使用 built-in benches");

    // 示例基准测试结构（注释形式）
    /*
    #![feature(test)]
    extern crate test;

    #[bench]
    fn bench_function(b: &mut test::Bencher) {
        b.iter(|| {
            // 要测试的代码
            expensive_function()
        })
    }
    */

    println!("\n基准测试最佳实践:");
    println!("- 在发布构建中运行");
    println!("- 多次运行取平均值");
    println!("- 避免测试 I/O 操作");
    println!("- 使用真实数据集");
}

/// 4. 配置 (Configuration)
///
/// 使用配置信息自定义构建过程
pub fn configuration() {
    println!("\n=== 配置 (Configuration) ===");

    // 检查配置
    if cfg!(debug_assertions) {
        println!("调试构建");
    } else {
        println!("发布构建");
    }

    // 目标架构配置
    if cfg!(target_arch = "x86_64") {
        println!("x86_64 架构");
    }

    // 操作系统配置
    if cfg!(target_os = "windows") {
        println!("Windows 系统");
    }

    // 特性配置
    if cfg!(feature = "enable_debug") {
        println!("调试功能已启用");
    }

    println!("\n配置信息用途:");
    println!("- 条件编译");
    println!("- 平台特定代码");
    println!("- 特性开关");
    println!("- 构建优化");
}

/// 5. 自定义错误信息 (Custom Error Messages)
///
/// 使用属性提供更详细的错误信息
pub fn custom_error_messages() {
    println!("\n=== 自定义错误信息 ===");

    // 自定义编译错误信息
    #[cfg(feature = "nonexistent")]
    compile_error!("该特性不存在，请检查 Cargo.toml");

    // 自定义弃用信息
    #[deprecated(since = "1.0.0", note = "请使用 `new_api` 替代，它提供了更好的性能和安全性")]
    fn old_api() {
        println!("旧 API");
    }

    println!("自定义错误信息:");
    println!("- compile_error! 宏生成编译时错误");
    println!("- 详细的弃用说明");
    println!("- 清晰的迁移指南");
}

/// 6. 代码生成 (Code Generation)
///
/// 使用元数据驱动代码生成
pub fn code_generation() {
    println!("\n=== 代码生成 ===");

    // 使用 derive 自动生成代码
    #[derive(Debug, Clone, PartialEq)]
    struct Person {
        name: String,
        age: u32,
    }

    let person = Person { name: "Alice".to_string(), age: 30 };

    println!("自动生成的 Debug 实现: {:?}", person);

    // 克隆
    let person2 = person.clone();
    println!("克隆相等: {}", person == person2);

    println!("\n代码生成工具:");
    println!("- derive 属性自动生成 trait 实现");
    println!("- 宏系统生成复杂代码");
    println!("- build.rs 构建时生成代码");
    println!("- procedural macros 生成代码");
}

/// 7. 元编程 (Metaprogramming)
///
/// 使用宏和其他元编程技术
pub fn metaprogramming() {
    println!("\n=== 元编程 ===");

    // 声明宏
    macro_rules! create_function {
        ($func_name:ident) => {
            fn $func_name() {
                println!("函数 {} 已创建", stringify!($func_name));
            }
        };
    }

    // 使用宏创建函数
    create_function!(dynamic_function);

    // 调用动态创建的函数
    dynamic_function();

    println!("元编程技术:");
    println!("- 声明宏 (macro_rules!)");
    println!("- 过程宏 (proc macros)");
    println!("- 属性宏");
    println!("- 函数式宏");
    println!("- 代码生成");
}

/// 主演示函数
pub fn demonstrate_meta() {
    documentation();
    attributes();
    benchmarking();
    configuration();
    custom_error_messages();
    code_generation();
    metaprogramming();
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_documentation() {
        documentation();
    }

    #[test]
    fn test_attributes() {
        attributes();
    }

    #[test]
    fn test_configuration() {
        configuration();
    }

    #[test]
    fn test_code_generation() {
        #[derive(Debug, Clone, PartialEq)]
        struct TestStruct {
            value: i32,
        }

        let s1 = TestStruct { value: 42 };
        let s2 = s1.clone();
        assert_eq!(s1, s2);
    }

    #[test]
    fn test_metaprogramming() {
        // 测试宏创建的函数
        macro_rules! test_macro {
            ($func_name:ident) => {
                fn $func_name() -> i32 {
                    42
                }
            };
        }

        test_macro!(test_function);
        assert_eq!(test_function(), 42);
    }

    #[test]
    fn test_demonstrate_meta() {
        demonstrate_meta();
    }
}
